---
title: "Troubleshoot: missing SYS_PTRACE capability"
sidebarTitle: "SYS_PTRACE"
description: ""
icon: "circle-exclamation"
---

Subtrace requires the `SYS_PTRACE` Linux capability in order to work correctly.

Expand the environment you're using to find the exact change to make.

<AccordionGroup>
  <Accordion title="Docker (docker run)">
    If you're using Subtrace in a Docker container via `docker run`, add `--cap-add=SYS_PTRACE` when starting your container. For example:

    ```bash
    docker run -it --rm --cap-add=SYS_PTRACE debian:12
    ```
  </Accordion>

  <Accordion title="Docker Compose">
    Add `cap_add: [SYS_PTRACE]` to your service in `compose.yaml`:

    ```yaml {5-6}
    services:
      my-app:
        image: ghcr.io/NAMESPACE/IMAGE_NAME:latest
        command: "subtrace run -- ./start.sh"
        cap_add:
          - SYS_PTRACE
    ```
  </Accordion>

  <Accordion title="Kubernetes (Deployments/Pods)">
    Add the capability in the container `securityContext`:

    ```yaml {18-21}
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: my-deployment
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: my-app
      template:
        metadata:
          labels:
            app: my-app
        spec:
          containers:
          - name: my-container
            image: ghcr.io/NAMESPACE/IMAGE_NAME:latest
            securityContext:
              capabilities:
                add:
                  - SYS_PTRACE
    ```
  </Accordion>

  <Accordion title="Amazon ECS (Fargate)">
    The ECS console UI does not expose `linuxParameters.capabilities`. Create a new task definition revision and edit the JSON to include `SYS_PTRACE`:

    ```json
    "linuxParameters": {
      "capabilities": {
        "add": ["SYS_PTRACE"]
      }
    },
    ```

    ![Open JSON editor](/images/ecs/5-task-update-button.png)

    ![Highlighted JSON changes](/images/ecs/6-task-json-diff.png)
  </Accordion>

  <Accordion title="Flightcontrol">
    Add the `linuxCapabilities` section to your `flightcontrol.json`:

    ```json {3-4}
    "target": {
      "type": "fargate",
      "linuxCapabilities": {
        "add": ["SYS_PTRACE"]
      }
    }
    ```
  </Accordion>

</AccordionGroup>
